SPEC-PWF-OPS · v0.1
14 June 2026
Owner: Platform team

Service operations

The ongoing loop once a device is live: agreement renews on each device's own cadence, incidents resolve against the SLA that agreement sets, field engineers execute the on-site visits, and invoices issue and settle. This is the manual for the operations sub-hierarchy — four lifecycles, three of them interlocking through a single thread: a device's maintenance agreement.

1The four lifecycles

One process per document. Agreement keeps each device's maintenance agreement continuous; incident response turns a telemetry breach into a resolved alarm; field visit is the engineer's on-site execution of a scheduled visit; invoice lifecycle takes a charge from issued to paid. They begin where quote-to-cash ends — a commissioned device with its first agreement.

2How the loops interlock

The three agreement-threaded lifecycles are not independent — a device's maintenance agreement is the thread that ties them. Agreement sets the tier; incident response freezes its SLA from that tier at ticket creation; billing invoices its period. Field visit composes within incident and agreement — the engineer's execution of the visit they schedule. Each loop runs on its own cadence, per device or per organization.

• Agreement → incident. A service ticket freezes its SLA from the device's agreement tier at creation (DM-19) — so the agreement a customer holds is exactly what incident response honors, even if the agreement later moves or lapses.
• Agreement → billing & sales. Agreements are per device, each with its own PeriodEnd; ahead of every period end Agreement signals Sales the renewal opportunity (agreement.expiring) and Billing the period to invoice. The derived PartnerCustomer — and its access grant — lives exactly while agreement exists.
• Upstream of the model. Incident response begins at alert.raised; the telemetry plane that evaluates thresholds sits outside Postgres (PTL-1 ⚠). Billing is organization-scoped — the riversync tenant has none — and currency always comes from the BillingProfile (THB for the reference orgs), never assumed.

3Maintenance lifecycle

Per-device agreement: attach, hold, expire, renew or move, lapse. A device can move to a new partner at its own renewal; the partner link and its access track agreement exactly. Full detail is in the maintenance drill-down (SPEC-PWF-MNT).

4Incident response

Telemetry breach → alarm → remote fix or engineer visit → resolved, with the conversation thread recording it. The ticket's SLA is frozen from the device's agreement tier at creation. Full detail is in the incident drill-down (SPEC-PWF-INC).

5Field visit

The engineer's on-site execution of the visit that incident or agreement schedules: dispatch → check-in → corrective or preventive work → parts & evidence → customer sign-off, offline-first. One source per visit — a service ticket or a maintenance plan, never both. Full detail is in the field-visit drill-down (SPEC-PWF-FLD).

6Invoice lifecycle

Issued → due → paid, or escalated to accounting follow-up when overdue. Organization-scoped; currency from the BillingProfile. Full detail is in the billing drill-down (SPEC-PWF-BIL).

7Rules in play

The WF-rules that bind the operating lifecycles — the master holds the full set. Note WF-7: scope- and channel-sensitive steps defer to the single resolvers (Agreement owns partner scope, SVC-6) rather than re-deciding inline.

8Traceability & open questions

What each lifecycle realizes and the events it rides; no step stands without evidence (WF-2). The ⚠ gaps match the master ERD and PRD.

Lifecycle	Realizes	Rides events
Maintenance lifecycle	PRT-1 · PRT-2 · PRT-8	agreement.attached · .expiring · .renewed · .moved · partner-link.lapsed
Incident response	PTL-1 ⚠ · PTL-2 · PTL-4 · PTL-5	alert.raised · .acknowledged · ticket.created · visit.scheduled · device.command-executed
Field visit	FLD-1…9 · DM-27…31	visit.scheduled · visit.checked-in · visit.completed · maintenance.due
Invoice lifecycle	ACC-3 · ADM-3	invoice.issued · invoice.overdue

• ⚠ PTL-1 — the telemetry plane is upstream of the model. Incident response begins at alert.raised; threshold evaluation lives outside Postgres and is not a workflow step here.
• ⚠ ACC-6 — no notifications consumer. The overdue invoice emits invoice.overdue with no dunning-delivery step — the same gap onboarding's invite hits. Each loop marks the step rather than inventing a channel.
• SLA on move. When a device's agreement moves to a new partner, open tickets keep the SLA frozen at creation (DM-19) — agreement changes do not retroactively re-tier live incidents.

9Revision history

Version	Date	Changes
0.1	14 Jun 2026	First draft — the operating lifecycles become a sub-hierarchy of the workflow set (SPEC-PWF-OPS). This overview/manual joins agreement (SPEC-PWF-AGR), incident response (SPEC-PWF-INC) and invoice lifecycle (SPEC-PWF-BIL), now grouped under workflow/operate/. No change to the lifecycles themselves.
0.2	14 Jun 2026	Field visit (SPEC-PWF-FLD) joins the group as the fourth lifecycle — the engineer's on-site execution for the new Field app (SPEC-APP-FLD); composes within incident and agreement (WF-8). Now four lifecycles.